home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / pil50kit.zip / CFILES / PILAPI.C < prev    next >
Text File  |  1992-04-09  |  58KB  |  1,702 lines
  1. /* ----------------------------------------------------------------------------    */
  2. /*    Originators:                                                                */
  3. /*      Tom Arnold,    Quark, Inc.,    300 S. Jackson,     Denver,     CO 80209    */
  4. /*        Ron Perry,     Atex, Inc.,        165 Lexington Road,    Billerica,     MA 01821    */
  5. /* ----------------------------------------------------------------------------    */
  6. /*    The source code in this file is provided by Quark and Atex for use in the    */
  7. /*    development of a Publishing Interchange Language. The code provided herein    */
  8. /*    is non-proprietary, non-copyrighted, and is for use in the public domain.    */
  9. /*    The source code contained herein is provided "as is".                        */
  10. /* ----------------------------------------------------------------------------    */
  11. /*    QUARK AND ATEX DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, WITH REGARD    */ 
  12. /*    TO THE ENCLOSED SOURCE CODE. QUARK AND ATEX DISCLAIM ANY IMPLIED WARRANTY,    */
  13. /*    INCLUDING, BUT NOT LIMITED TO ANY IMPLIED WARRANTY OF FITNESS FOR A            */
  14. /*    PARTICULAR PURPOSE OR MERCHANTABILITY.                                        */
  15. /* ----------------------------------------------------------------------------    */
  16.  
  17.  
  18. /*$ab ----------------------------- abstract ----------------------------------
  19.   pilapi.c       Contains interface routines for applications to access the pil
  20.                   parser and generator.
  21.                   
  22.                   NO MEMORY IS ALLOCATED OR FREED BY THE FUNCTIONS IN THIS MODULE!
  23.                   
  24.                   NO I/O (FILE OPENS, CLOSES, READS, OR WRITES, ERROR PRINTING)
  25.                   IS DONE DIRECTLY BY THE FUNCTIONS IN THIS MODULE.
  26.  
  27.                   ERRORS ARE COMMUNICATED TO THE APPLICATION BY RETURNING AN
  28.                   ERROR CODE AND SETTING A GLOBAL ERROR WORD WITH THAT ERROR CODE. 
  29.                   
  30.                   A function is provided to return the last PIL_ERROR set.
  31.                   
  32.                   The functions in this module manipulate a buffer that is 
  33.                   provided by the application. The parser/generator functions
  34.                   use memory from the buffer sequentially, and keep track of 
  35.                   what is used, by calling pil_alloc. However, there is no 
  36.                   corresponding pil_free to give back parts of the buffer. It
  37.                   is the application's responsibility to provide a buffer that
  38.                   is big enough for the structures being built. When the buffer
  39.                   is not large enough, PIL_OUT_OF_MEMORY will be returned by
  40.                   the function that requested memory. It is then up to the 
  41.                   application to provide a larger buffer, call pil_set_buffer,
  42.                   and retry. In the case of parsing, PIL_OUT_OF_MEMORY requires 
  43.                   restarting the parser at the beginning of the file.
  44.                   
  45.                   The application also provides pointers to functions to read
  46.                   and write characters.  The application must open the 
  47.                   necessary files for reading or writing the PIL, and set up the 
  48.                   getchar or putchar function pointers, and provide a buffer for
  49.                   the parser, before calling any function here that needs to read 
  50.                   or write! (This is be done with pil_pg_init.)
  51.                   
  52.                   The application can call the functions here to:
  53.                       read a pil file, putting pil structures into a buffer
  54.                       create pil structures in a buffer
  55.                       write pil structures from the buffer to a file
  56.                       write comments to a file
  57.                       
  58.                    The functions that read or create pil structs will put structures 
  59.                   at the next available location in the provided buffer, 
  60.                   and return an error code (PIL_ERROR). A pointer to the structure
  61.                   written, will be returned in a parameter passed to the function.
  62.  
  63.                   
  64.     Major functions for parsing and generating:
  65.     ------------------------------------------
  66.      
  67.         pil_pg_init                Initializes parser and generator
  68.         pil_get_component        Read the next thing from the file and put it in
  69.                                 the pil buffer.
  70.         pil_put_component        Write a pil_component to the open pil file
  71.         pil_create_component    Create a component of the requested type in the 
  72.                                 pil buffer at the next available location. This
  73.                                 allocates space in the buffer, clears it, and sets
  74.                                 up the structure with language-specific defaults. 
  75.  
  76.  
  77.     Utility functions for controlling parser/generator actions:
  78.     ----------------------------------------------------------
  79.     
  80.         pil_set_asa_list        Set up a list of application-specific-attributes
  81.                                 (asa) that the application wants the parser to 
  82.                                 return, ignoring all others.
  83.         pil_set_buffer            Set up the buffer that will be used for reads.
  84.         pil_set_cnt_bsize        Set the content data buffering size. This value is
  85.                                 initialized at pil_pg_init() time and can be modified
  86.                                 via this function.
  87.         pil_set_getc            Set get character function pointer
  88.         pil_set_putc            Set put character function pointer
  89.  
  90.  
  91.     Utility functions for status:
  92.     ----------------------------
  93.     
  94.         pil_get_mem_avail        Returns the number of bytes left in the pil buffer
  95.         pil_last_error            Returns the most recent PIL_ERROR
  96.         pil_get_version            Returns the language version and api version strings.
  97.         pil_get_line_num        Returns the line number where the parser encountered
  98.                                 an error.
  99.  
  100.  
  101.     Utility functions for creating PIL data structures:
  102.     --------------------------------------------------
  103.     
  104.         pil_alloc                   Allocates memory from the pil buffer
  105.         pil_create_asi                Create an application specific item
  106.         pil_create_asa                Create an application specific attribute
  107.         pil_create_pvalue            A pil_value for a pil_asa
  108.         pil_create_nametbleentry     A name table entry
  109.         pil_create_objid            an object id (for text flow or group)
  110.         pil_create_pathpt            A path point (for a pil_path)
  111.         pil_create_polypt            A polygon point
  112.         pil_create_layout_start        Create layout start component
  113.         pil_create_name_table        Create name table component
  114.         pil_create_canvas            Create canvas component
  115.         pil_create_object            Create object component
  116.         pil_create_text_flow        Create text flow component
  117.         pil_create_group            Create group component
  118.         pil_create_layout_end        Create layout end component
  119.         pil_create_content_start    Create content start component
  120.         pil_create_content_hdr        Create content header component
  121.         pil_create_content_data        Create content data component
  122.         pil_create_content_end        Create content end component
  123.  
  124.  
  125.     Utility functions for PIL file generation:
  126.     -----------------------------------------
  127.     
  128.         pil_put_comment            Write a comment into the pil file
  129.         pil_put_layout_start    Write a layout start component
  130.         pil_put_name_table        Write a name table component
  131.         pil_put_canvas            Write a canvas component
  132.         pil_put_object            Write a object component
  133.         pil_put_text_flow        Write a text flow component
  134.         pil_put_group            Write a group component
  135.         pil_put_layout_end        Write a layout end component
  136.         pil_put_content_start    Write a content start component
  137.         pil_put_content_hdr        Write a content header component
  138.         pil_put_content_data    Write a content data component
  139.         pil_put_content_end        Write a content end component
  140. ---------------------------------------------------------------------------- */
  141.  
  142.  
  143. /*$au ------------------------------ audits -----------------------------------
  144.     Author: Tom Arnold
  145.             Quark, Inc.
  146.             300 South Jackson
  147.             Denver, Colorado 80209
  148.             (303) 934-2211
  149.  
  150.     Ver     Date       Who  Etc
  151.     v01.02  24-apr-91  tla    Upgraded for PIL 5.0
  152.     v01.01  03-apr-91  tla    Fixed 2 bugs in pil_set_buffer, one in pil_alloc,
  153.         that could allow pointers to improper address boundaries, and allow
  154.         the buf to be overrun by several bytes. Changed pil_api_ver to b01.01
  155.     v01.00  12-feb-91  tla    Initial version
  156. ---------------------------------------------------------------------------- */
  157.  
  158.  
  159. /*$ep --------------------------- header files ---------------------------- */
  160.  
  161. #ifdef        THINK_DA    /* Support for THINK C Desk Accessory Architecture     */
  162. #include     <SANE.h>    /* Pickup num2str                                     */
  163. #else                    /* else                                             */
  164. #include    <stdlib.h>    /* Use stdlib for atof                                */
  165. #endif                    /* end of THINK_DA                                     */
  166. #include    "pildefs.h"    /* Pick up PIL data structures and defines            */
  167.  
  168.  
  169.  
  170.  
  171. /*$ed ------------------------ public global data -------------------------- */
  172.  
  173. #ifdef PIL_ANSI_PROTOTYPES
  174. ex